<!DOCTYPE html>
<html lang="en">
<head>
  <title>Vert.x Http Service Factory - Vert.x</title>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta content="width=device-width, initial-scale=1.0" name="viewport">
  <meta content="Vert.x is a tool-kit for building reactive applications on the JVM." name="description">
  <link href="http://vertx.io/stylesheets/docs.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/stylesheets/font-awesome.min.css" media="screen" rel="stylesheet">
  <link href="http://vertx.io/javascripts/styles/rainbow.min.css" media="screen" rel="stylesheet">
  <!-- IE 6-8 support of HTML 5 elements -->
  <!--[if lt IE 9]>
  <script src="http://static.jboss.org/theme/js/libs/html5/pre3.6/html5.min.js"></script>
  <![endif]-->

  <link rel="apple-touch-icon" sizes="57x57" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-57x57.png">
  <link rel="apple-touch-icon" sizes="60x60" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-60x60.png">
  <link rel="apple-touch-icon" sizes="72x72" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-72x72.png">
  <link rel="apple-touch-icon" sizes="76x76" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-76x76.png">
  <link rel="apple-touch-icon" sizes="114x114" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-114x114.png">
  <link rel="apple-touch-icon" sizes="120x120" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-120x120.png">
  <link rel="apple-touch-icon" sizes="144x144" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-144x144.png">
  <link rel="apple-touch-icon" sizes="152x152" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-152x152.png">
  <link rel="apple-touch-icon" sizes="180x180" href="http://vertx.io/assets/favicons/vertx-favicon-7/apple-touch-icon-180x180.png">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-32x32.png" sizes="32x32">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/android-chrome-192x192.png" sizes="192x192">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-96x96.png" sizes="96x96">
  <link rel="icon" type="image/png" href="http://vertx.io/assets/favicons/vertx-favicon-7/favicon-16x16.png" sizes="16x16">
  <link rel="manifest" href="http://vertx.io/assets/favicons/vertx-favicon-7/manifest.json">
  <link rel="mask-icon" href="http://vertx.io/assets/favicons/vertx-favicon-7/safari-pinned-tab.svg" color="#5bbad5">
  <meta name="msapplication-TileColor" content="#7d3194">
  <meta name="msapplication-TileImage" content="http://vertx.io/assets/favicons/vertx-favicon-7/mstile-144x144.png">
  <meta name="theme-color" content="#ffffff">

  <link href="http://fonts.googleapis.com/css?family=Ubuntu:400,500,700,400italic" rel="stylesheet" type="text/css">
  <link rel="alternate" type="application/rss+xml" title="RSS"
     href="http://vertx.io/feed.xml">
  <script>
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
    ga('create', 'UA-30144458-1', 'auto');
    ga('create', 'UA-71153120-1', 'auto', 'tracker');
    ga('send', 'pageview');
    ga('tracker.send', 'pageview');
  </script>
</head>
<body>

<a href="http://www.reactivemanifesto.org/" id="reactive-manifesto-banner">
  <img style="border: 0; position: fixed; right: 0; top:0; z-index: 9000"
    src="http://d379ifj7s9wntv.cloudfront.net/reactivemanifesto/images/ribbons/we-are-reactive-black-right.png">
</a>

<a id="skippy" class="sr-only sr-only-focusable" href="#content"><div class="container"><span class="skiplink-text">Skip to main content</span></div></a>

<header class="navbar navbar-default navbar-static-top" id="top" role="banner">
  <div class="container">
    <div class="navbar-header">
      <button class="navbar-toggle collapsed" type="button" data-toggle="collapse" data-target="#vertx-navbar-collapse">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <a href="http://vertx.io/" class="navbar-brand"><img alt="Brand" src="http://vertx.io/assets/logo-sm.png"></a>
    </div>
    <nav class="collapse navbar-collapse" id="vertx-navbar-collapse">
      <ul class="nav navbar-nav navbar-right">
        <li><a href="http://vertx.io/download/">Download</a></li>
        <li><a href="http://vertx.io/docs/">Documentation</a></li>
        <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
        <li><a href="http://vertx.io/community/">Community</a></li>
        <li><a href="http://vertx.io/materials/">Materials</a></li>
        <li><a href="http://vertx.io/blog/">Blog</a></li>        
      </ul>
    </nav>
  </div>
</header>



  <div class="page-header" id="content">
    <div class="container">
      <div class="row">
        <div class="col-sm-12">
          <h1>Vert.x Http Service Factory</h1>
          
        </div>
      </div>
    </div>
  </div>




<div id="content">
  <div class="container docs-content">
    <div class="row">
      <div class="col-sm-12 col-md-push-9 col-md-3 hidden-xs hidden-sm">
        <div id="sidebar" data-spy="affix">
          <ul class="sectlevel1">
<li><a href="#_deploying_a_java_service_packaged_as_a_fatjar">Deploying a Java service packaged as a fatjar</a></li>
<li><a href="#_http_client_configuration">Http client configuration</a>
<ul class="sectlevel2">
<li><a href="#_client_authentication">Client authentication</a></li>
<li><a href="#_proxy_server_configuration">Proxy server configuration</a></li>
</ul>
</li>
<li><a href="#_public_key_servers">Public key servers</a></li>
<li><a href="#_validation_policy">Validation policy</a></li>
<li><a href="#_cache_directory">Cache directory</a></li>
<li><a href="#_examples">Examples</a>
<ul class="sectlevel2">
<li><a href="#_bintray">Bintray</a></li>
<li><a href="#_service_zip">Service zip</a></li>
<li><a href="#_bintray_hosting">Bintray hosting</a></li>
</ul>
</li>
</ul>
        </div>
      </div>
      <div class="col-sm-12 col-md-pull-3 col-md-9">
        <div class="toc hidden-md hidden-lg">
          <h2>Table of Contents</h2>
          <ul class="sectlevel1">
<li><a href="#_deploying_a_java_service_packaged_as_a_fatjar">Deploying a Java service packaged as a fatjar</a></li>
<li><a href="#_http_client_configuration">Http client configuration</a>
<ul class="sectlevel2">
<li><a href="#_client_authentication">Client authentication</a></li>
<li><a href="#_proxy_server_configuration">Proxy server configuration</a></li>
</ul>
</li>
<li><a href="#_public_key_servers">Public key servers</a></li>
<li><a href="#_validation_policy">Validation policy</a></li>
<li><a href="#_cache_directory">Cache directory</a></li>
<li><a href="#_examples">Examples</a>
<ul class="sectlevel2">
<li><a href="#_bintray">Bintray</a></li>
<li><a href="#_service_zip">Service zip</a></li>
<li><a href="#_bintray_hosting">Bintray hosting</a></li>
</ul>
</li>
</ul>
        </div>
        <div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>The http service factory is a Vert.x service factory for deploying services from an http server.</p>
</div>
<div class="paragraph">
<p>It it an alternative
to the Maven Service Factory for using services hosted on a plain http server, e.g a JavaScript service zipped
and hosted somewhere. Unlike the Maven Service Factory, the Http Service Factory does not provide any kind of
classpath dependency resolution. To use this feature be sure that <code>io.vertx:vertx-http-service-factory:3.3.3</code> is in your classpath.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>vertx run https://myserver.net/myverticle.zip::my-service</pre>
</div>
</div>
<div class="paragraph">
<p>Although it looks like an http URL, it is a verticle identifier with a factory bound to the <em>https</em> prefix (<em>http</em>
also supported).</p>
</div>
<div class="paragraph">
<p>The service identifier is made up of the suffix to form an <em>http</em> URL or the archive that contains the service,
followed by a double colon <code>::</code> and a service name.</p>
</div>
<div class="paragraph">
<p>The service name is used to find the service descriptor file inside the artifact which is named by the service name with
a <code>.json</code> extension. This is explained in the <a href="http://vertx.io/docs/vertx-service-factory/java">Service Verticle Factory</a>
documentation.</p>
</div>
<div class="paragraph">
<p>For example, to deploy a service that exists in an hosted at <code><a href="https://myserver.net/myverticle.zip" class="bare">https://myserver.net/myverticle.zip</a></code> called <code>my-service</code>
you would use the string <code><a href="https://myserver.net/myverticle.zip::my-service" class="bare">https://myserver.net/myverticle.zip::my-service</a></code>.</p>
</div>
<div class="paragraph">
<p>Given this string, the verticle factory will use the Vert.x http client try and download the resource
<code><a href="https://myserver.net/myverticle.zip" class="bare">https://myserver.net/myverticle.zip</a></code>.</p>
</div>
<div class="paragraph">
<p>It then constructs a classpath including this archive and creates a classloader with that classpath in order
to load the service using the standard <a href="http://vertx.io/docs/vertx-service-factory/java">Service Verticle Factory</a>.</p>
</div>
<div class="paragraph">
<p>The Service Verticle Factory will look for a descriptor file called `my-service.json on the constructed classpath to
actually load the service.</p>
</div>
<div class="paragraph">
<p>Given a service identifier the service can be deployed programmatically e.g.:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>vertx.deployVerticle("https://myserver.net/myverticle.zip::my-service", ...)</pre>
</div>
</div>
<div class="paragraph">
<p>Or can be deployed on the command line with:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>vertx run https://myserver.net/myverticle.zip::my-service</pre>
</div>
</div>
<div class="paragraph">
<p>The service name can be omitted when the service jar <code>META-INF/MANIFEST</code> contains a `Main-Verticle`entry that
declares the verticle to run:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>vertx.deployVerticle("https://myserver.net/myverticle.zip", ...)</pre>
</div>
</div>
<div class="paragraph">
<p>And the manifest contains:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>Main-Verticle: service:my.service</pre>
</div>
</div>
<div class="paragraph">
<p>Of course it can be deployed on the command line with:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>vertx run https://myserver.net/myverticle.zip</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_deploying_a_java_service_packaged_as_a_fatjar">Deploying a Java service packaged as a fatjar</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The deployer factory can also deploy a Java service packaged as a fatjar, i.e a jar that contains a Java service and all the classes needed
to run, for example:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>the jar manifest contains the <code>Main-Verticle:myservice.json</code></p>
</li>
<li>
<p><code>myservice.json</code> declares the service via <code>main:my.Verticle</code></p>
</li>
<li>
<p>the class <code>my.Verticle</code></p>
</li>
<li>
<p>all the classes needed by the verticle to run, for example Google Guava jar, etc&#8230;&#8203;</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_http_client_configuration">Http client configuration</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Files are downloaded using Vert.x http client, by default the https client is configured with the <code>ssl=true</code>
and <code>trustAll=true</code>. The default client options can be overriden to use specific configurations with the
<em>vertx.httpServiceFactory.httpClientOptions</em> system property and the <em>vertx.httpServiceFactory.httpsClientOptions</em>
system property, these properties are valid for any http resource.</p>
</div>
<div class="sect2">
<h3 id="_client_authentication">Client authentication</h3>
<div class="paragraph">
<p>The client supports basic authentication via the <em>vertx.httpServiceFactory.authUsername</em> and
<em>vertx.httpServiceFactory.authPassword</em> system properties.</p>
</div>
<div class="paragraph">
<p>Authentication is done only for services (i.e basic authentication will not be done for key servers) and only using
an https connection.</p>
</div>
</div>
<div class="sect2">
<h3 id="_proxy_server_configuration">Proxy server configuration</h3>
<div class="paragraph">
<p>The http client can be configured to support a proxy server with the <em>vertx.httpServiceFactory.proxyHost</em> and
<em>vertx.httpServiceFactory.proxyPort</em> system properties.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_public_key_servers">Public key servers</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Signed artifacts signatures are verifed using a public key, public key are retrieved from a public key server.</p>
</div>
<div class="paragraph">
<p>The public key server uri can be configured with the <em>vertx.httpServiceFactory.keyserverURITemplate</em> system property.
The URI template is used to create the public key URI this way:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>String.format(keyserverURITemplate, signature.getKeyID())</pre>
</div>
</div>
<div class="paragraph">
<p>When the property is not set, the default public key server is the <em>SKS OpenPGP Public Key Server</em> server used and
the uri template used is : <code><a href="http://pool.sks-keyservers.net:11371/pks/lookup?op=get&amp;options=mr&amp;search=0x%016X" class="bare">http://pool.sks-keyservers.net:11371/pks/lookup?op=get&amp;options=mr&amp;search=0x%016X</a></code>
this server will server public key resources with the <em>application/pgp-keys</em> media type.</p>
</div>
<div class="paragraph">
<p>The Json <a href="https://keybase.io/docs/api/1.0/call/key/fetch">format</a> sent by Keybase.io is also support. Keybase.io
can be used as a public key server with <code><a href="https://keybase.io/_/api/1.0/key/fetch.json?pgp_key_ids=%016X" class="bare">https://keybase.io/_/api/1.0/key/fetch.json?pgp_key_ids=%016X</a></code> URI template.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_validation_policy">Validation policy</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The validation policy governs how downloaded services are validated, the <em>vertx.httpServiceFactory.validationPolicy</em>
system property configures the behavior of the verticle factory when it attemps to deploy a downloaded service file:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><em>none</em> : the service file is just deployed as is</p>
</li>
<li>
<p><em>verify</em> : the service file is verified when there is a corresponding <em>.asc</em> signature file, otherwise it is
not verified. If the signature cannot be verified, the deployment fails.</p>
</li>
<li>
<p><em>mandatory</em>: the service file must have a corresponding <em>.asc</em> signature file and the signature must be verified.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The default validation policy is <strong><em>verify</em></strong>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_cache_directory">Cache directory</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The cache directory stores the files used by the http service factory after download:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>deployed services</p>
</li>
<li>
<p>service signatures</p>
</li>
<li>
<p>public keys</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The cached files are named after the percent encoded download URL:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>-rw-r--r--  1 julien  staff   270 May  3 21:44 http%3A%2F%2Flocalhost%3A8080%2Fthe_verticle.zip
-rw-r--r--  1 julien  staff   473 May  3 21:44 http%3A%2F%2Flocalhost%3A8080%2Fthe_verticle.zip.asc
-rw-r--r--  1 julien  staff  1768 May  3 21:44 http%3A%2F%2Flocalhost%3A8081%2Fpks%2Flookup%3Fop%3Dget%26options%3Dmr%26search%3D0x9F9358A769793D09</pre>
</div>
</div>
<div class="paragraph">
<p>The default cache directory <em>.vertx</em> can be set to a specific location with the <em>vertx.httpServiceFactory.cacheDir</em>
system property.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_examples">Examples</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_bintray">Bintray</h3>
<div class="paragraph">
<p>Bintray is a distribution platform that can be used for hosting files.</p>
</div>
</div>
<div class="sect2">
<h3 id="_service_zip">Service zip</h3>
<div class="listingblock">
<div class="content">
<pre>&gt; echo 'console.log("hello world")' &gt; helloworld.js
&gt; echo '{"main":"helloworld.js"}' &gt; helloworld.json
&gt; zip helloworld.zip helloworld.json helloworld.js</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_bintray_hosting">Bintray hosting</h3>
<div class="paragraph">
<p>Assuming you have a Bintray account:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>create a Bintray repository with the <em>generic</em> type, for instance <em>testgenrepo</em></p>
</li>
<li>
<p>in this repository create a package, for instance <em>testpkg</em></p>
</li>
<li>
<p>optionally edit the package and check the <em>GPG sign uploaded files using Bintray&#8217;s public /private key pair.</em></p>
</li>
<li>
<p>in this package create a version, for instance <em>1.0</em></p>
</li>
<li>
<p>now upload the <em>helloworld.zip</em> file</p>
</li>
<li>
<p>publish the files</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The file are now hosted with an URL like : <em><a href="https://bintray.com/artifact/download/vietj/testgenrepo/helloworld.zip" class="bare">https://bintray.com/artifact/download/vietj/testgenrepo/helloworld.zip</a></em></p>
</div>
<div class="paragraph">
<p>If you have configured the GPG signature, you will have also the signature file <em><a href="https://bintray.com/artifact/download/vietj/testgenrepo/helloworld.zip.asc" class="bare">https://bintray.com/artifact/download/vietj/testgenrepo/helloworld.zip.asc</a></em>.
It will be by default downloaded and validated with <a href="http://pool.sks-keyservers.net:11371/pks/lookup?op=vindex&amp;fingerprint=on&amp;search=0x379CE192D401AB61">Bintray&#8217;s public key</a></p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="paragraph">
<p>Of course you can use your own keys for signing the files.</p>
</div>
</div>
</div>
<div class="paragraph">
<p>We can run this service with:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>vertx run https://bintray.com/artifact/download/vietj/testgenrepo/helloworld.zip::helloworld
% Hello World
Succeeded in deploying verticle</pre>
</div>
</div>
</div>
</div>
</div>

        

        
          <div id="footer">
            <div id="footer-text">
              
                Last updated 2016-09-12 08:38:04 CEST
              
              
            </div>
          </div>
        
      </div>
    </div>
  </div>
</div>

<footer>
  <div class="container">
    <div class="row">
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Vert.x</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/">Home</a></li>
          <li><a href="http://vertx.io/download/">Download</a></li>
          <li><a href="http://vertx.io/docs/">Documentation</a></li>
          <li><a href="https://github.com/vert-x3/wiki/wiki">Wiki</a></li>
          <li><a href="http://vertx.io/blog/">Blog</a></li>
          <li><a href="http://vertx.io/vertx2/" class="vertx-2-link">Vert.x 2</a></li>
        </ul>
      </div>
      <div class="col-xs-6 col-sm-3 col-md-3 col-lg-2">
        <h2>Community</h2>
        <ul class="list-unstyled">
          <li><a href="http://vertx.io/community/">Help &amp; Contributors</a></li>
          <li><a href="http://vertx.io/materials/">Learning materials</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx">User Group</a></li>
          <li><a href="https://groups.google.com/forum/?fromgroups#!forum/vertx-dev">Developer Group</a></li>
        </ul>
      </div>

      <div class="col-xs-12 col-sm-6 col-lg-offset-2 col-md-6 copyright">
        <p>Vert.x is open source and dual licensed under the <a href="https://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License 1.0</a> and <a href="https://www.apache.org/licenses/LICENSE-2.0.html">Apache License 2.0</a>.</p>
        <p>This website is licensed under the <a href="http://creativecommons.org/licenses/by-sa/3.0/">CC BY-SA 3.0 License</a>.<br>
        Design by <a href="http://www.michel-kraemer.com">Michel Kr&auml;mer</a>. <a href="http://www.entypo.com">Entypo pictograms</a> by Daniel Bruce.</p>
        <div class="row">
          <div class="col-xs-12 col-lg-offset-1 col-md-5">
            <a href="http://eclipse.org">
            <img class="logo eclipse-logo" src="http://vertx.io/assets/eclipse_logo_grey_small.png" width="204" height="48">
            </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-0 col-md-5">
            <a href="http://cloudbees.com">
            <img class="logo cloudbees-logo" src="http://vertx.io/assets/Button-Built-on-CB-1-grey.png" width="180" height="48">
           </a>
          </div>
          <div class="col-xs-12 col-md-offset-2 col-lg-offset-1 col-md-5 jprofiler">
            <a href="http://www.ej-technologies.com/products/jprofiler/overview.html"
            style="text-decoration:none">
            <img class="logo jprofiler-logo" src="http://vertx.io/assets/jprofiler-logo.png" width="48" height="48"><span class="jprofiler-logo">&nbsp; JPROFILER</span>
            </a>
          </div>
        </div>
      </div>
    </div>
  </div>
</footer>

<script src="http://static.jboss.org/theme/js/libs/jquery/jquery-1.9.1.min.js"></script>
<script src="http://vertx.io/javascripts/bootstrap.min.js"></script>
<script src="http://vertx.io/javascripts/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>



<script src="http://vertx.io/javascripts/sidebar.js"></script>


</body>
</html>
